VejalNai Chatbot: Product & QA Documentation

1. Executive Summary

VejalNai Chatbot is a customer engagement platform designed to automate responses and manage customer communication across multiple channels (Web, Facebook, WhatsApp, Instagram). It provides a real-time admin inbox, automated bot handoffs, user profile mapping, and location/device tracking. Recent iterations have polished it into a SaaS-ready live chat engine with high responsiveness, robust error recovery, and seamless layout flow.

2. Product Features & Architecture

A. Real-Time Admin Inbox Dashboard

• Dynamic Thread List: Displays active user sessions, sorted by latest message timestamp, with visual indicators for conversation status (Open, Pending Human Handoff) and communication channel source.
• AJAX-Based Message Composer: Enables live agent replies without reloading the page. Submissions are processed as JSON payloads, and messages append optimistically for instant feedback.
• Automatic Input Resizing: Textareas expand dynamically up to 150px when typing long messages and shrink back to a single line on message dispatch.
• Keyboard Shortcuts: Pressing Enter automatically submits the composer form, while Shift + Enter inserts a new line.

B. Customer-Side Chat Widget (widget.js)

• Zero-Dependency Script: Built in lightweight vanilla JS, preserving page performance.
• Session Persistence: Automatically tracks visitor sessions via sessionStorage (vejalnai_visitor_id). Sessions stay intact across redirects/page reloads and map to a persistent database Contact.
• Initialization Settings: Allows clients to define custom user configurations when loading the widget:

  window.VejalNaiChat = {
      widgetKey: 'widget_public_key',
      name: 'Zahid Hasan',
      email: 'zahid@example.com'
  };

• Dynamic Name Commands: Anonymous visitors can define or update their profile names on the fly using inline chat commands:
  • /name John Doe
  • /নাম জাহিদ হাসান
  The bot updates the profile database instantly and returns a confirmation response.

C. Live Activity & Device Tracking (Crisp-Like Live Assist)

• Active Page Tracking: The widget script reports parent page URLs (window.location.href) during history load and message dispatches.
• Visual Device Mockup: A styled smartphone graphic in the sidebar details block displays the visitor's active domain inside a mini browser address bar, and active page path they are browsing currently.
• Region fallback: Automatically falls back to Bangladesh (main target region) for anonymous profiles.
• Timezone Conversion: Automatically shifts UTC server datetimes to the local Asia/Dhaka timezone (GMT+6) so the admin dashboard timestamps align perfectly with the agent's laptop time.

3. QA Defect Log & Resolutions

4. Engineering Best Practices

1. Server-Side Rendered (SSR) Partials: Rather than coding heavy, complex JS engines to update the conversation sidebar list, we implemented SSR HTML updates. Polling calls /conversations-sidebar and replaces the list container's inner HTML, making the UI robust and easy to maintain.
2. API Fetch Locks: Prevented race-conditions and overlapping queries by introducing fetch state locks (isLoadingHistory) in the widget scripts.
3. Strict Security Authorization: Added backend route authorization checks to verify the authenticated user has active membership inside the conversation's organization before returning private message histories.

5. Future Roadmap & Recommendations

• Laravel Reverb/WebSockets: Transition from 3s/5s polling to WebSockets (using Laravel Reverb or Pusher) to minimize HTTP request overhead and achieve instant transmission.
• IP Geolocation Integration: Connect a geolocation provider API to automatically resolve customer location details based on client IP instead of defaulting statically to Bangladesh.
• Typing Indicators: Broadcast client keystrokes using small fetch events to trigger active typing indicators on both sides of the window.